Skip to main content

Initialize Payment Collection​

Initiate a payment request to generate a unique payment reference, payment code and checkout URL for your customers

POST https://api.spotflow.co/api/v1/payments/initialize

Headers

authorization
String

Bearer SECRET_KEY
Include your secret key in the request header as a Bearer token for authorization. Unauthorized requests will result in a 401 HTTP status code.

content-type
String		application/json

Body Parameters

reference
String

Specify a unique reference ID generated by your company to identify each customer.

amount
Integer		Amount should be in the subunit of our supported currency i.e your local currency or USD.
currency
String		Select the currency for the payments charge. Can either be in USD or in the local currency of your collection region.
localCurrency
String		This in the local currency of your region. Used only when currency is set to USD. According to the local region, this can either be in NGN, GHS or KSH.
customer email
String		The customer’s email address
metadata
String		This is information pertaining to additional details about your product or service. Under metadata, you have productName" as a field — This is necessary for you to add as it indicates the name of your product and helps to specify to your user what your product is called. You can add any other additional field as you deem fit.

Sample Request Body for NGN Payment

{
    "reference": "ref-{{$randomUUID}}",
    "planId": "7de59939-b303-4ead-8cdb-a7d28f40159d", // when paying for a subscription plan 
    "amount": 2, //not needed when paying for a subscription plan
    "currency": "USD",
    "localCurrency": "NGN", // not needed when currency is not set to USD, according to the local region, this can either be in NGN, GHS or KSH
    "metadata": {
        "productName": "Daily Mail",
        "title": "Creator"
    },
    "callBackUrl": "https://www.algoai.one", // optional if a callback url has been set on your dashboard
    "customer": {
        "email": "customer@email.com",
        "name": "Dee",
        "phoneNumber": "{{$randomPhoneNumber}}"
    }
}

Sample Response for NGN Payment

200 OK 

{
    "reference": "ref-0ac20954-43f4-4a71-b808-3fb0960d0949",
    "checkoutUrl": "https://checkout.spotflow.co/SRg0jnDWcAN1kxb",
    "paymentCode": "SRg0jnDWcAN1kxb",
    "status": "pending",
    "callBackUrl": "https://www.algoai.one",
    "metadata": {
        "title": "Creator",
        "productName": "Daily Mail"
    }
}

Sample Request Body for GHS Payment

{
    "reference": "ref-{{$randomUUID}}",
    "planId": "7de59939-b303-4ead-8cdb-a7d28f40159d", // only when paying for a subscription plan 
    "amount": 5,
    "currency": "GHS", 
    "localCurrency": "GHS", // not needed when currency is not set to USD, according to the local region, this can either be in NGN, GHS or KSH
    "channel": "mobile_money",
    "customer": {
        "email": "customer@email.com"
    },
    "callBackUrl": "https://www.algoai.one", // optional if a callback url has been set on your dashboard
    "metadata": {
        "companyName": "AlgoRand",
        "SubscriptionPlan": "MonthlyPass"
    }
}

Sample Response for GHS Payment

200 OK 

{
    "reference": "ref-6bc7890-43f4-4a71-b808-3fb0960d0949",
    "checkoutUrl": "https://checkout.spotflow.co/SRg0jnDWcAN1kxb",
    "paymentCode": "PQf0jnDWcAN1kxb",
    "status": "pending",
    "callBackUrl": "https://www.algoai.one",
    "metadata": {
        "title": "AlgoRand",
        "productName": "Monthly Pass"
    }
}

Complete test payment or redirect users for live payment by taking them to the checkout URL. Confirm the payment collection outcome via the webhook URL set up on your dashboard or by using our Verify Payment Collection Endpoint.